//+------------------------------------------------------------------+
//|                                                  ICollection.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+

//+------------------------------------------------------------------+
//| ICollection<T> 泛型接口：MQL5 通用集合操作标准接口                |
//| 核心定位：定义泛型集合（可存储任意数据类型）的基础操作规范，      |
//|           为数组、链表、哈希表等具体集合类提供统一的操作接口，    |
//|           实现“接口归一化”，降低不同集合类的使用与替换成本       |
//| 泛型特性：通过模板参数 <T> 支持任意数据类型（如 int、double、自定义结构/类），|
//|           无需为每种数据类型重复定义集合接口，提升代码复用性       |
//| 核心价值：作为“抽象契约”，隔离集合的“使用逻辑”与“实现细节”，    |
//|           开发者可基于接口编写通用代码（如遍历、筛选集合），无需关心 |
//|           底层是数组还是链表，适配 EA 中各类数据管理场景（如订单列表、 |
//|           信号过滤链、持仓集合等）                                 |
//| 适用场景：所有需要统一管理一组同类数据的 MQL5 程序（EA、指标、脚本），|
//|           尤其适合数据动态增删、批量操作、跨集合类型兼容的场景       |
//+------------------------------------------------------------------+
template<typename T>
interface ICollection
  {
   //----------------------------------------------------------------
   // 数据添加接口：向集合中插入元素
   //----------------------------------------------------------------
   /**
    * @brief 向集合末尾添加一个元素
    * @param value [in] 待添加的元素（类型与泛型参数 T 一致）
    * @return bool - 添加结果：true=添加成功（元素符合集合规则，如未超出容量限制），false=添加失败（如容量不足、元素无效）
    * @note 具体实现需处理：
    *       1. 元素合法性校验（如自定义类需检查指针有效性）；
    *       2. 集合扩容（如动态数组需自动扩展容量）；
    *       3. 重复元素处理（根据具体集合规则决定是否允许重复，如链表允许、哈希表不允许）。
    */
   bool      Add(T value);

   //----------------------------------------------------------------
   // 数据访问接口：获取集合基础信息
   //----------------------------------------------------------------
   /**
    * @brief 获取集合中当前存储的元素数量
    * @return int - 元素数量（≥0，空集合返回0）
    * @note 是集合的核心属性，为遍历、容量判断等操作提供基础
    */
   int       Count(void);

   /**
    * @brief 检查集合中是否包含指定元素
    * @param item [in] 待检查的元素（类型与泛型参数 T 一致）
    * @return bool - 检查结果：true=集合中存在该元素，false=不存在
    * @note 具体实现需定义“元素相等”的判断逻辑：
    *       1. 基础类型（int、double 等）：直接值比较；
    *       2. 自定义类型（结构/类）：需通过重载 == 运算符或自定义比较逻辑实现。
    */
   bool      Contains(T item);

   //----------------------------------------------------------------
   // 数据复制接口：将集合元素批量复制到外部数组
   //----------------------------------------------------------------
   /**
    * @brief 将集合中的元素复制到外部数组（从集合起始位置开始复制）
    * @param dst_array [out] 目标数组（需提前分配足够空间，类型与 T 一致）
    * @param dst_start [in] 目标数组的起始复制索引（默认从0开始，即数组首位置）
    * @return int - 实际复制的元素数量（≤集合元素总数，若目标数组空间不足，仅复制可容纳的元素）
    * @note 关键约束：
    *       1. 目标数组必须是“引用传递”（&dst_array[]），否则无法修改外部数组；
    *       2. 需确保目标数组在 dst_start 之后的空间 ≥ 集合元素数量，避免数组越界；
    *       3. 复制顺序与集合内部元素顺序一致（如数组按索引递增，链表按插入顺序）。
    */
   int       CopyTo(T &dst_array[], const int dst_start=0);

   //----------------------------------------------------------------
   // 数据清理与删除接口：修改集合内容
   //----------------------------------------------------------------
   /**
    * @brief 清空集合中所有元素，重置为初始空状态
    * @note 具体实现需：
    *       1. 释放动态分配的内存（如链表需逐个删除节点并释放内存）；
    *       2. 重置元素计数（Count() 调用后返回0）；
    *       3. 保留集合的基础配置（如容量上限、比较规则等），便于后续重新添加元素。
    */
   void      Clear(void);

   /**
    * @brief 从集合中删除指定元素（仅删除第一个匹配项）
    * @param item [in] 待删除的元素（类型与泛型参数 T 一致）
    * @return bool - 删除结果：true=删除成功（找到并移除元素），false=删除失败（集合为空或无匹配元素）
    * @note 具体实现需：
    *       1. 先通过 Contains() 逻辑找到匹配元素的位置；
    *       2. 移除元素并调整集合结构（如数组需前移后续元素，链表需修改节点指针）；
    *       3. 若集合允许重复元素，仅删除第一个匹配项，后续重复元素保留。
    */
   bool      Remove(T item);
  };
//+------------------------------------------------------------------+